Skip to content

feat: add fire + executions subgroup (parity with @cueapi/mcp 0.4.0)#24

Merged
govindkavaturi-art merged 1 commit intomainfrom
feat/fire-and-execution-tools
May 3, 2026
Merged

feat: add fire + executions subgroup (parity with @cueapi/mcp 0.4.0)#24
govindkavaturi-art merged 1 commit intomainfrom
feat/fire-and-execution-tools

Conversation

@mikemolinet
Copy link
Copy Markdown
Collaborator

@mikemolinet mikemolinet commented May 2, 2026

Same change as the (now-closed) fork PR #23. Re-opened from an upstream branch so CI workflows can access secrets and auto-merge can fire.

Summary

Brings cueapi-cli to parity with @cueapi/mcp 0.3.0 + 0.4.0 surface for fire-cue and worker-execution-lifecycle operations.

What's added

One top-level command:

  • cueapi fire <cue-id> [--payload-override JSON] [--merge-strategy merge|replace]

One new subgroup with seven commands:

  • cueapi executions list historical executions
  • cueapi executions list-claimable [--task] [--agent] server-side SQL filter
  • cueapi executions get <id> single-row fetch
  • cueapi executions claim <id> --worker-id ID atomic claim
  • cueapi executions claim-next --worker-id ID [--task] internal fan-out when --task
  • cueapi executions heartbeat <id> --worker-id ID X-Worker-Id header transport
  • cueapi executions report-outcome <id> --success/--failure [...] write-once outcome

Notable design choices

  • list-claimable uses server-side query params, not client-side filter. Client-side filter after fetch hits the LIMIT 50 starvation bug fixed in the 2026-04-25 prod incident (see app/routers/executions.py:122-131 docstring in cueapi-core for the prior repro).
  • claim-next --task fans out via list-claimable + claim by ID since the server's POST /v1/executions/claim endpoint does not accept a task filter today.
  • heartbeat sends worker_id via the X-Worker-Id request header, not body. --worker-id is required at the CLI even though server permits omission.

Tests

pytest tests/ 36 pass (was 19, +17 new help-text + arg-parsing tests). No live API calls.

Version

0.1.5 -> 0.2.0. Aligned cueapi/init.py (had drifted to 0.1.3) with pyproject.toml at the same time.

@mikemolinet @claude
feat: add fire + executions subgroup (parity with @cueapi/mcp 0.4.0)
0af5b47 
Brings the CLI to parity with the @cueapi/mcp 0.3.0 + 0.4.0 surface for
the fire-cue and worker-execution-lifecycle operations.

New top-level command:
- cueapi fire <cue-id> [--payload-override JSON] [--merge-strategy merge|replace]
  Wraps POST /v1/cues/{id}/fire. For ad-hoc one-shot triggers and for
  using cues as a messaging channel between agents.

New executions subgroup with seven subcommands:
- executions list
- executions list-claimable [--task] [--agent]   server-side SQL filter
- executions get <id>
- executions claim <id> --worker-id ID
- executions claim-next --worker-id ID [--task]   internal fan-out when --task
- executions heartbeat <id> --worker-id ID        X-Worker-Id header transport
- executions report-outcome <id> --success/--failure [--external-id ...]

Notes:
- list-claimable uses server-side query params for the task / agent filter,
  not client-side. Client-side filter after fetch hits the LIMIT 50
  starvation bug fixed in the 2026-04-25 prod incident (see app/routers/
  executions.py:122-131 docstring in cueapi-core).
- claim-next with --task fans out via list-claimable + claim by ID since
  the server's POST /v1/executions/claim endpoint does not accept a task
  filter today. Tiny race window between list and claim is bounded by the
  atomic claim returning 409, in which case the caller retries.
- heartbeat sends worker_id via the X-Worker-Id request header, not body.
  --worker-id is required even though the server permits omission, so
  misconfigured callers fail at the CLI instead of silently bypassing the
  race-protection check.

Version: 0.1.5 -> 0.2.0. Aligned cueapi/__init__.py (had drifted to 0.1.3)
with pyproject.toml at the same time.

Tests: 36 pass (was 19, +17 new help-text + arg-parsing tests for the new
commands following the existing pattern).

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
@govindkavaturi-art govindkavaturi-art enabled auto-merge (squash) May 2, 2026 01:18
mikemolinet
mikemolinet commented May 2, 2026
View reviewed changes
Copy link
Copy Markdown
Collaborator Author

@mikemolinet mikemolinet left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Cue-Pm reviewed and approved.

@govindkavaturi-art
Copy link
Copy Markdown
Member

govindkavaturi-art commented May 3, 2026

Diff LGTM — clean parity work mirroring @cueapi/mcp@0.3.0 (fire) plus a comprehensive executions subgroup that closes the worker-transport receive→claim→process→complete loop. Quick notes after a read-through:

What's strong here

  • fire correctly leaves merge_strategy unset by default and lets the API's Pydantic default (merge) apply. Direct learning from MCP fix: update pypi-publish to v1.13.0 for Metadata 2.4 support #9 review feedback — the description explicitly says "default: merge, server-side".
  • executions list-claimable --task / --agent uses the server-side SQL filter from cueapi/cueapi#392. The CHANGELOG note about single-purpose worker starvation under the LIMIT 50 window is exactly right.
  • executions claim-next --task is honest about the fan-out workaround (filtered list → pick oldest → claim by ID) since the server's /claim endpoint doesn't accept a task filter. Good comment trail.
  • --payload-override validates JSON before sending — fails fast on the client side with a clear UsageError, never reaches the server malformed.
  • Version drift fix is appreciated (__init__.py was 0.1.3, pyproject.toml was 0.1.5; both now 0.2.0).

On the auto-merge FAILURE in the check rollup
Not a real blocker. That run (25239174897) is stale history from PR #23 on the same branch — ${{ github.event.pull_request.number }} evaluated to 23 there because the event was associated with the now-closed sibling PR, not #24. The workflow file itself (on both this branch and main) is already correct: uses github.event.pull_request.number properly + GH_TOKEN from secrets.GOVIND_GITHUB_TOKEN. Run 25240146110 is the latest for #24 and is SUCCESS end-to-end. Branch protection picks the latest, so no follow-up PR needed.

Only real blocker
Branch protection requires required_approving_review_count: 1. Once an approving review lands (Govind / a CODEOWNER), auto-merge fires immediately — it's already armed via the gh pr merge --auto call.

One small framing note (nit, ship anyway)
The CHANGELOG line "for using cues as a messaging channel between agents" is the same workaround framing we softened away from in MCP #9. Once the messaging primitive ships in the dashboard / docs, this CLI command should just be "fire an existing cue immediately" — the messaging-via-cue-payload pattern is what the Phase 12.1.5 messaging primitive in cueapi-core@messaging-v1.0.0 is designed to replace. Not blocking; just worth a follow-up CHANGELOG tweak when the messaging primitive surfaces officially.

🤖 Reviewed by Claude Code — comment only, awaiting human approval to merge.

@govindkavaturi-art govindkavaturi-art merged commit 9220bbb into main May 3, 2026
7 of 8 checks passed
@govindkavaturi-art govindkavaturi-art deleted the feat/fire-and-execution-tools branch May 3, 2026 18:24
@mikemolinet mikemolinet mentioned this pull request May 3, 2026
Open
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

No reviews

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@mikemolinet @govindkavaturi-art